docs(adk): audit foundations and concept pages by jacksonyzj · Pull Request #444 · botpress/docs

jacksonyzj · 2026-04-01T00:23:46Z

Summary

Audit and update all foundation and concept pages to match ADK v1.17. Verified against runtime source code (agent-lack repo) and shipped @botpress/runtime@1.17.0 types.

Tickets

#	Ticket	Page
1	ADK-287	Introduction
2	ADK-288	Quickstart
3	ADK-289	Project Structure
4	ADK-292	Conversations
5	ADK-290	Actions
6	ADK-294	Tables
7	ADK-295	Triggers
8	ADK-296	Knowledge
9	ADK-291	Tools
10	ADK-293	Workflows (merged 2 pages → 1)

Key changes

Fixed inaccurate code examples and API signatures
Removed non-existent APIs and unreleased features
Added missing documentation for shipped features
Merged the two workflow pages into one
Updated quickstart to match current adk init flow

See individual Linear tickets for detailed change lists.

Test plan

Preview via Mintlify staging deployment
Cross-check all code examples against @botpress/runtime@1.17.0 shipped types
Verified all internal links resolve
Tested by separate AI agent reading local .mdx files against running ADK bot

mintlify · 2026-04-01T00:23:50Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
botpress	🟢 Ready	View Preview	Apr 1, 2026, 12:29 AM

…287)

…ns (ADK-292)

adk/concepts/tables.mdx

…-293)

…signature (ADK-292, ADK-293, ADK-296)

…and ADK scripts

jacksonyzj · 2026-04-06T13:31:59Z

Actions are also callable from outside the agent via the Botpress API.

The generated AdkClient (client-wrapper.ts:346-358) wraps client.callAction() — which is a Botpress API call. So any external system with a valid bot client can invoke actions the same way:

client.callAction({ type: 'lookupOrder', input: { orderId: '123' } })

Additionally, adk run scripts can call actions from outside the normal agent runtime (via the actions proxy in actions.ts, which also uses client.callAction for integration actions).

So the accurate statement would be: Actions are callable from workflows, conversations, other actions, external API clients, and ADK scripts.

Fixed!

jacksonyzj · 2026-04-06T13:33:39Z

Would be nice to tie into Control Panel Stuff with the primitives: i.e.

Invoking / testing actions and workflows from the control panel interacting with tables on dev and prod in the tables view, managing sync status and sync requests, etc

Noted! Will add these cross references as soon as add the control panel page!

jacksonyzj · 2026-04-06T13:36:20Z

we should prompt them to open up the control panel earlier.
would be nice to also introduce them to the agentsteps screen here.

No evals yet in this release! We can wait it till next release to add it!

jacksonyzj · 2026-04-06T14:00:48Z

we should prompt them to open up the control panel earlier.
would be nice to also introduce them to the agentsteps screen here.

Good suggestions! I moved the control panel above adk chat, also include a screenshot for agent steps.

jacksonyzj · 2026-04-06T14:25:14Z

Should this be part of project structure?

I put it here as a quick intro since it ties to agent.config.ts. But the full deep dive will be in the dedicated State and Configuration pages which I'm gonna add in the next PR.

chloequijano-botpress

feedback after some of the changes

adk/concepts/actions.mdx

adk/concepts/conversations.mdx

adk/concepts/workflows.mdx

chloequijano-botpress · 2026-04-06T15:59:55Z

adk/quickstart.mdx

-```bash bun
-bun install
-```
+- `agent.config.ts` — Agent configuration, state schemas, and integration dependencies


the problem is that this page is more of a "quickstart" so it should just be instructions for getting started quickly instead of needing to read long texts like this. If they want more details they have the Project Structure as the next page

chloequijano-botpress · 2026-04-06T16:00:55Z

adk/quickstart.mdx

-```bash bun
-bun install
-```
+- `agent.config.ts` — Agent configuration, state schemas, and integration dependencies


^ more of an opinion but happy to have someone else jump in if they disagree so I'll have it unresolved for now

adk/quickstart.mdx

…et() input

…rsations, actions, workflows

…bility

docs(adk): audit and update quickstart for ADK 1.17

9ca3478

mintlify bot deployed to staging April 1, 2026 00:29 View deployment

docs(adk): update quickstart init flow, fix Control Panel naming

d7dd155

mintlify bot deployed to staging April 1, 2026 01:20 View deployment

docs(adk): audit introduction page, remove unused message param (ADK-…

24bd398

…287)

mintlify bot deployed to staging April 1, 2026 13:13 View deployment

docs(adk): audit project structure page (ADK-289)

f8b2b22

mintlify bot deployed to staging April 1, 2026 13:23 View deployment

docs(adk): audit conversations page (ADK-292)

466bb49

mintlify bot deployed to staging April 1, 2026 13:38 View deployment

docs(adk): add Conversation.get(), instance properties to conversatio…

cb33242

…ns (ADK-292)

mintlify bot deployed to staging April 1, 2026 13:41 View deployment

docs(adk): audit actions page, fix tool example (ADK-290)

2d50333

mintlify bot deployed to staging April 1, 2026 14:56 View deployment

docs(adk): audit and update tables page (ADK-294)

5e0d646

mintlify bot deployed to staging April 1, 2026 15:03 View deployment

github-actions bot reviewed Apr 1, 2026

View reviewed changes

adk/concepts/tables.mdx Show resolved Hide resolved

docs(adk): audit knowledge page, add search method (ADK-296)

70cfd36

mintlify bot deployed to staging April 1, 2026 18:35 View deployment

docs(adk): audit tools page, fix src/tools reference (ADK-291)

e6d1045

mintlify bot deployed to staging April 1, 2026 19:11 View deployment

docs(adk): merge workflows into single page, add missing methods (ADK…

541b580

…-293)

mintlify bot deployed to staging April 1, 2026 19:38 View deployment

docs(adk): move workflows.mdx out of folder (ADK-293)

ba381ce

mintlify bot deployed to staging April 1, 2026 19:40 View deployment

jacksonyzj changed the title ~~docs(adk): update ADK documentation~~ docs(adk): audit existing pages — foundation + concepts (PR 1) Apr 1, 2026

jacksonyzj changed the title ~~docs(adk): audit existing pages — foundation + concepts (PR 1)~~ docs(adk): audit foundations and concept pages Apr 1, 2026

docs(adk): fix unreleased search(), wildcard message type, provide() …

0c7db79

…signature (ADK-292, ADK-293, ADK-296)

mintlify bot deployed to staging April 2, 2026 14:48 View deployment

docs(adk): expand actions intro — callable from external API clients …

16c585c

…and ADK scripts

mintlify bot deployed to staging April 6, 2026 13:32 View deployment

docs(adk): move Control Panel before adk chat, mention Chat view

510af32

mintlify bot deployed to staging April 6, 2026 13:38 View deployment

docs(adk): add Control Panel screenshot to quickstart

a3decb8

mintlify bot deployed to staging April 6, 2026 13:45 View deployment

docs(adk): reword tools intro — convention first, flexibility second

73ba235

mintlify bot deployed to staging April 6, 2026 14:19 View deployment

chloequijano-botpress reviewed Apr 6, 2026

View reviewed changes

docs(adk): remove vague ADK scripts reference, clarify Conversation.g…

c14cc5f

…et() input

mintlify bot deployed to staging April 6, 2026 18:37 View deployment

docs(adk): simplify chat prop description and handler parameters wording

ac04d74

mintlify bot deployed to staging April 6, 2026 18:44 View deployment

docs(adk): add default temperature value (0.7)

5525e0c

mintlify bot deployed to staging April 6, 2026 18:47 View deployment

docs(adk): add named export example for conversations

5e9ab19

mintlify bot deployed to staging April 6, 2026 18:48 View deployment

docs(adk): replace vague tools wording with cross-references to conve…

e70adab

…rsations, actions, workflows

mintlify bot deployed to staging April 6, 2026 18:54 View deployment

docs(adk): restore deploy wording, break Control Panel text for reada…

5eda56a

…bility

mintlify bot deployed to staging April 6, 2026 18:57 View deployment

docs(adk): replace quickstart file list with link to Project Structure

df6be7a

mintlify bot deployed to staging April 6, 2026 19:01 View deployment

docs(adk): clarify maxAttempts error catching and step.listen parameter

8586448

mintlify bot deployed to staging April 6, 2026 19:03 View deployment

Conversation

jacksonyzj commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Tickets

Key changes

Test plan

Uh oh!

mintlify bot commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

jacksonyzj commented Apr 6, 2026

Uh oh!

jacksonyzj commented Apr 6, 2026

Uh oh!

jacksonyzj commented Apr 6, 2026

Uh oh!

jacksonyzj commented Apr 6, 2026

Uh oh!

jacksonyzj commented Apr 6, 2026

Uh oh!

chloequijano-botpress left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chloequijano-botpress Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

chloequijano-botpress Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jacksonyzj commented Apr 1, 2026 •

edited

Loading

mintlify bot commented Apr 1, 2026 •

edited

Loading